Configuring a Message Broker

This topic describes how to configure a Message Broker.

Startup Parameters

Each Message Broker has an INI file that contains startup parameters:

ActiveMQMessageBroker.ini.This file must be located under the <Message Broker Installation folder>/Conf.

Microsoft Windows platforms	This folder is typically at C:\Program Files\Micro Focus\ActiveMQ Message Broker\
Linux platforms	/opt/MessageBroker

Parameters that may need to be changed based on your needs are described in the next sections.

Configuring a Message Broker Cloud

If you plan to run more than one Message Broker, they probably should be configured into a cloud.

To create a Message Broker cloud, do the following:

If you have not already done so, install the Message Brokers. Refer to the MPX Message Broker installation for instructions.
For each Message Broker you want to include in the cloud, open the associated ActiveMQMessageBroker.ini file in a text editor.
Add or edit the following line to list all the Message Brokers you want to include in the cloud:
```
server_names=tcp://servername:endpoint
```
where
- servername is the TCP/IP address or computer name where the remote Message Broker is installed.
- endpoint is the port number on which the remote Message Broker is listening (61616 is the default Message Broker port).
Separate multiple addresses by a comma (,). For example, the following line creates a cloud consisting of three Message Brokers: the current Message Broker and the two Message Brokers listed below.
```
server_names=tcp://ProdServer1:61616,tcp://ProdServer2:61620		
```
Tip: If a Message Broker operating outside of a firewall must participate with Message Brokers behind a firewall, an inside Message Broker should be directed to establish contact with the outside Message Broker, because the firewall may prohibit the establishment of the connection in the reverse direction.

Save and close the file.

The next time you start the Message Broker, it will establish connections with the Message Brokers listed in the server_names parameter.

Changing the Endpoint of a Message Broker

The endpoint (port number) of a Message Broker is specified when you install it. If you later want to configure a Message Broker to use a different endpoint, you must edit the ActiveMQMessageBroker.ini file.

To change the endpoint number of a Message Broker, do the following:

Make the change to the ActiveMQMessageBroker.ini file for that Message Broker:

Open the ActiveMQMessageBroker.iniSTMessageBroker68.ini file in a text editor.

Add or edit the following line:

conn_names=tcp://servername:endpoint

where:

servername	Is the TCP/IP address or name of the computer where the Message Broker runs; you can use the keyword “_node” 0.0.0.0 to designate the primary IP address of the local host independent of its host name. You can use the keyword "_any" to have the Message Broker listen on all available IP addresses of the local host.
endpoint	Is the new endpoint you want the Message Broker to use. Default is 61616.

Save and close the file. Your changes will take effect the next time you start the Message Broker

If this Message Broker is part of a Message Broker cloud, be sure to edit the ActiveMQMessageBroker.ini files associated with the other Message Brokers in the cloud.

For each server configuration that has one or more profiles that use this Message Broker, create or edit each profile using one of the following methods (this technique works only if the server has successfully started in MPX mode):

Use the Server Administration to edit the affected profiles:

From Server Administration, select the server configuration.
Click Tools >Administration > Configure Server.
From the Event Handlers tab, select ActiveMQ MPX Transmitter as the event handler.
From the Profile list, select an affected profile.
Click Modify to open the Event Handlers Profile Properties dialog box.
In the Profile Properties list, double-click server_names.
In the Event Handler Property dialog box, edit the appropriate endpoints in the Property Value field.

Your changes take effect the next time you start the server configuration.

Edit the associated MPXEventTransmitter.xml file directly

This technique should be used when the server is not currently running or not running in MPX mode.

Open the MPXEventTransmitter.xml file in a text editor.
Edit the server_names parameter in each affected unicast profile to reflect the new endpoint.
Save and close the file.

Your changes take effect the next time you start the server configuration.

For each MPX Cache Agent that accesses this Message Broker, edit the MessageBroker group to change the appropriate server_names parameter.

Open the MPX Cache Agent’s XML file in a text editor.
Find the server_names parameter for the correct Message Broker. For example, it might look like the following: <server_names>tcp:12.34.56.78:61616</server_names>
Change the endpoint/port number portion of that line.

Configuring Two Message Brokers in a Fail-Over Configuration

Normally, only one Message Broker receives initial messages from a server configuration's transmitters. However, for load-balancing or in a fail-over configuration, you can use two Message Brokers as the "root" Message Broker. The following procedure describes where to install and how to configure these two Message Brokers. One can go on the server machine with the second on a network-near machine or both Message Brokers can be on network-near machines. Both Message Brokers can even be on the same machine if they used different port numbers.

The network-near machine (or machines) will not compete with StarTeam Server for memory and network bandwidth. Since the Message Broker is not especially CPU or memory bound, the system requirements for the second machine can be quite minimal. For example, a 1-CPU Pentium with ~512MB of memory is sufficient; however, 2 CPUs (or a Pentium-HT) and 1GB of memory is ideal. Note that, the Message Broker will crash if it runs out of memory.

To deploy and configure two Message Brokers on separate server machines, do the following:

Install two Message Brokers on separate server machines but network-near to the StarTeam Server, and set each to point to the other by adding the line:
```
server_names=tcp://other_server:61616
```
to the ActiveMQMessageBroker.ini file, where other_server is the IP address of the "other" Message Broker server machine.
Open the StarTeam configuration's Event Transmitter configuration file (typically MPXEventTransmitter.xml) in a text editor, and change the default client and server profiles to randomly select between the two Message Brokers:
```
<server_names>_random, tcp:box1:61616, tcp:box2:61616</server_names>
```
where box1 and box2 are the IP addresses of the two Message Broker server machines.
This setting causes both the MPX Event Transmitter and all local clients to randomly select one of the two Message Brokers. Furthermore, if one of them fails (for example, it faults, is turned off, or disconnected from the network), everyone connected to that Message Broker will fail-over to the other Message Broker. This also allows one box to be taken down for maintenance without bringing all of ActiveMQ MPX down.
Remote users should continue to use the MPX profile that points them to the network-nearest Message Broker.

Enabling Tracing for Message Brokers

If a Message Broker is failing for non-obvious reasons (for example, it isn't running or out of memory), you can turn on tracing by adding the following lines to its <Message Broker install folder>/conf/log4j.properties file:

log4j.rootLogger=DEBUG, console, logfile

By default, the log files are stored under <Message Broker install folder>/data/activemq.log. This can be changed by editing conf/log4j.properties file with the following line:

log4j.appender.logfile.file=${activemq.base}/data/activemq.log